fix: use pnpm rebuild to wire docs-toolkit bin under pnpm v11#7346
Merged
yomybaby merged 1 commit intoMay 11, 2026
Merged
Conversation
Amplify docs build was still failing with `Command "docs-toolkit" not found` even after #7342 dropped the stale pnpm@10 pin, because pnpm v11 treats a second `pnpm install --frozen-lockfile` against an already- satisfied lockfile as a no-op (~100ms `Already up to date`) and does NOT revisit bin link creation. The toolkit's `dist/cli.js` is generated between the two installs, so the second install is the only chance to turn the warning-skipped bin link into a real one — and v11 skips it. `pnpm rebuild` is the contract for "re-run link creation against the current node_modules layout" and works on both v10 and v11. Reproduced the failure and the fix locally against a clean clone of main HEAD: cd packages/backend.ai-webui-docs pnpm install --frozen-lockfile # warns: dist/cli.js missing pnpm --filter backend.ai-docs-toolkit run build pnpm rebuild # wires .bin/docs-toolkit pnpm --filter backend.ai-webui-docs exec docs-toolkit build:web \ --lang all --no-strict # succeeds, writes dist/web/
Member
Author
How to use the Graphite Merge QueueAdd either label to this PR to merge it via the merge queue:
You must have a Graphite account in order to use the merge queue. Sign up using this link. An organization admin has required the Graphite Merge Queue in this repository. Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue. This stack of pull requests is managed by Graphite. Learn more about stacking. |
yomybaby
deleted the
05-11-fix_use_pnpm_rebuild_to_wire_docs-toolkit_bin_under_pnpm_v11
branch
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the AWS Amplify build configuration for the docs site to correctly (re)create the docs-toolkit CLI bin link under pnpm v11 after the toolkit has been built, preventing pnpm exec docs-toolkit ... from failing in the later build phase.
Changes:
- Refines the preBuild rationale/commentary around pnpm v11 bin-link behavior for
backend.ai-docs-toolkit. - Replaces the second
pnpm install --frozen-lockfilewithpnpm rebuildto trigger bin-link (re)wiring afterdist/is produced.
Comment on lines
+137
to
+147
| # Subtle pnpm-v11 behavior: a second `pnpm install | ||
| # --frozen-lockfile` here is a no-op (`Already up to date`, | ||
| # ~100ms) because the lockfile is already satisfied — it | ||
| # does NOT revisit bin links. `pnpm rebuild` is what | ||
| # actually re-runs link creation against the now-populated | ||
| # `dist/`. Without this the later `pnpm exec docs-toolkit` | ||
| # call fails with `[ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL] | ||
| # Command "docs-toolkit" not found`. (Same chicken-and-egg | ||
| # pattern as FR-2719's build_docs job in package.yml and | ||
| # the docs-archive workflow; the v10→v11 bump in #7307 | ||
| # silently regressed the old install/build/install dance.) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #7342. The previous fix dropped a stale
pnpm@10pin inamplify.ymlbut the Amplify docs build kept failing with the same error:Root cause (verified locally)
backend.ai-docs-toolkitexposes its CLI viapackage.json#bin.docs-toolkit → ./dist/cli.js, butdist/cli.jsonly exists aftertscruns. The existingamplify.ymlflow tried to work around the chicken-and-egg by running install twice around the toolkit build:Reproducing on a clean
git cloneofmainHEAD with pnpm v11.0.8:In pnpm v11, the second install sees the lockfile already satisfied and exits in ~100 ms without re-running bin link creation. The first install's warning-skipped link stays broken.
--forcedoes not help (it still short-circuits on the satisfied lockfile). The v10→v11 bump in #7307 silently regressed this dance — v10 was apparently lenient here.Fix
Replace the second
pnpm install --frozen-lockfilewithpnpm rebuild, which is the documented mechanism for re-running link creation against the currentnode_modules. After this:dist/web/containsindex.html,next/,assets/,robots.txt, etc. — exactly the artifact Amplify expects.Why not just bake it into a postinstall
A
prepare/postinstallonbackend.ai-docs-toolkitwould invoketscfor every consumer, including local dev. Keeping the build orchestration in the deployment manifest is consistent with how the package.yml / docs-archive workflows already do it (the inline comment inamplify.ymlcross-references those). Only the secondinstallwas load-bearing for bin linking, andpnpm rebuildis the smaller, more honest tool for that job.